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Preface 


April 1979 


This handbook contains documentation for using all of the standard Mesa services intended for 
Mesa programmers as well as operational procedures for the Alto. In general, the sections are short 
and to the point, serving as a how-to guide rather than a reference document containing all of the 
details. This handbook assumes prior familiarity with the Mesa language as well as the Alto. All 
suggestions as to the form, correctness, and understandability of this document should be sent to 
your support group. 


This documentation is divided into 4 parts. Section 1 describes the basics needed to get started, 
Section 2 lists the directories that are of interest to Mesa users, Section 3 lists various resources you 
should be aware of, and Appendices A through F give further details on the Compiler, Binder, 
System, Debugger, Utilities, and RunMesa. 


The style of this handbook is similar to that used in the Mesa Language Manual. All fine points 
are in this font, user input/debugger output is in this font, file names are IN THIS FONT, and 
references to other documents are in this font. 


Section 1: Getting Started 


This section tells you all that you need to know for getting started and running a Mesa program. 
See the appendices for further details on the various subsystems and a sample debugging session. 


1.1. Setting up your Alto disk 


If you are setting up an Alto disk from scratch, either copy the standard Mesa disk maintained by 
your support group or obtain the command file MESADISK.CM, which transfers the basic runtime 
files, as well as Bravo (and a Mesa USER.CM file), to your Alto disk. You also need to install the Alto 
Operating System version 16/16, Executive 10, using erase option, before executing the command file: this should leave 
your disk with about 4000 free pages. If you just wish to get a new Mesa system on an already initialized 
disk, obtain the command file MESA.CM. Mesa 5.0 requires Alto Operating System version 16/16, Executive 10 
for proper operation. 


In either case, the basic Mesa runtime files that are transferred are: (1) RUNMESA.RUN, a BCPL 
program which loads the ram with the Mesa emulator, loads main memory with the kernel Mesa 
system, and starts execution, (2) MESA.IMAGE, the Mesa system, (3) COMPILER.IMAGE, the compiler, 
and (4) BINDER.IMAGE, the binder (5) XDEBUG.IMAGE, the debugger, and (6) the system definitions 
files. Note that you need approximately 1400 pages for all of the Mesa files plus about 850 pages for Bravo and 
related file. These command files also install the debugger (and Bravo). 


If the file MESAFONT.AL exists, Mesa will use it for the system display; otherwise SYSFONT.AL is used. 


1.2, Installing the debugger 


In order to establish the communication link between the debugger and the Mesa Executive, you 
must install the debugger. This installation is similar to installing the Swat debugger, for those familiar with that 
operation. Make sure your Alto disk contains the debugger, XDEBUG.IMAGE. 


The debugger is installed by typing XDebug to the Alto Executive. This saves the debugger’s core 
image on the file MESADEBUGGER and exits to the Alto Executive. If you want to load some of your own 
programs into the debugger, see Appendix D. The Debugger - Extended Features memo contains details on how to load 
user procs. 


1.3. Preparing your source file 


Mesa accepts both unformatted ASCII and formatted Bravo text files. Since the debugger uses 
source files to print source-text descriptions of the locus of the pc in frames and for setting 
breakpoints, be sure that the source files on your Alto disk are consistent with the object files. 
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1.4. Compiling your program 


Type Compiler to the Alto Executive to invoke the compiler. It prompts for the source file name; 
when it finishes, it prompts again; a null filename (CR) returns you to the Alto Executive. 
Alternately, you may type Compiler sourcei source2 .. . directly to the Alto Executive, 
making use of its filename completer if you wish. The compiler assumes a ".mesa” filename 
extension if one is not supplied. Compiled versions of all DEFINITIONS modules that your. program 
uses must be on your disk. 


If a syntactic error occurs, the compiler attempts to recover by deleting and/or inserting text (not in 
the file), logs the change(s), and tries to plow on. Semantic errors result in a symbolic print-out of 
the location of the error (in the form: procedure[character-position ]) and an indication of 
the type of error. The semantic passes try very hard to muddle through with a complete diagnosis. 
The compiler puts all error messages in the file sourcename.errtog. When compiled 
successfully, the resulting object file is found on sourcename.bcd. 


1.5. Binding your configuration 


Typing Binder to the Alto Executive invokes the binder. It prompts for the source file name; 
when it finishes, it prompts again; a null filename (CR) returns you to the Alto Executive. 
Alternately, you may type Binder sourcel sourced ... directly to the Alto Executive, making 
use of its filename completer if you wish. The binder assumes a". config" filename extension if 
one is not supplied. 


Compiled versions of all modules in your configuration must be on your disk. The binder goes 
through your configuration description, sourcename.config, and attempts to bind the 
IMPORTS/EXPORTS. All error messages are put in sourcename.erriog and the MESA.TYPESCRIPT 
file. When successfully bound, your sourcename.bcd file is ready to run. 


1.6. Running your program 


Type Mesa to the Alto Executive and you will find yourself talking to the Mesa Executive. Typing 
sourcename to the Alto Executive is the same as typing Mesa sourcename.bced. See the Executive Users’s Guide and 
Appendix C for more details. At system start-up the Mesa Executive is given control in a context from 
which all the various system utilities are visible. At this point, you are well advised to browse 
through the Afesa System Documentation for complete details on what you can do. Basically, you 
must: (1) load your program -- New command, and (2) execute its initialization code and start 
execution -- Start command. If this fails, try putting in some breakpoints or enabling some 
tracing before executing step (2). 


1.7. Debugging your program 


In order to set breakpoints in your program, trace program execution, display the runtime state, or 
interpret simple Mesa statements, you must first invoke the Mesa debugger; there are several ways 
of doing this. The straightforward method is to issue the Debug command to the Mesa Executive; 
this brings you into the debugger, ready to execute a command. If you wish to enter the debugger 
at any time (i.e., while your program is running), tSwaT interrupts your program. . Once you are 
inside the debugger, typing "?" to the command processor gives you a list of the valid commands. 
The Mesa Debugger Documentation contains details on other ways of entering the debugger and 
complete documentation on all the available commands. 
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1.8. Reporting problems 


Any requests or problems with the Mesa system should be sent to <SDSUPPORT>. Bug reports and 
messages that cannot be answered immediately are assigned a number and a state (open, closed, 
rejected, wish, or superseded) and filed in <SDSUPPORT>CR*.MSG. Whenever a change request is 
rejected or superseded, the originator is notified. Information about any change request (including 
a brief description and status) can always be found in <SDSUPPORT>CR*.LOG (" ::= 3]4|5, referring to 
the Mesa version number). 


Section 2: Directories 


These directories are maintained on [IRIS]. Users without access to this file server should consult 
their support group. 


<ALPHAMESA> 


Contains the new version of the Mesa system during the alpha test period. When the 
system is ready to be released, the contents of the <MESA> directory moves to <OLDMESA> 
and the contents of <ALPHAMESA> moves tO <MESA>. 


<MESA> 


Contains the IMAGE and BCD files of interest to users of the Mesa system. For files that are 
not so generally used, look in the appropriate subdirectories described below. 


<MESA>SYSTEM> 


Contains the source and object files for the system definitions and program modules. 
Several packages constructed from standard Mesa system modules are also stored here. 


<MESA>COMPILER> 
<MESA>BINDER> 
<MESA>XDEBUG> 
<MESADLISTER> 
<MESADUTILITIES> 
<MESADFTP> 

<MESA>PUP> (and FATPUP>) 


Contains the source and object files for the compiler, binder, debugger, lister, utility 
programs, ftp, and pup respectively. 


<MESA>DOC> 


Contains the documentation for the Mesa system; both .BRAVO and PRESS versions are 
maintained here. In addition, a variety of sample programs, including LEXICON (described 
in Chapter 7 of the Mesa Language Manual), can be found here. 


<MESALIB> 


An informal directory containing packages and independent subsystems along with 
corresponding documentation. The file SUMMARY.PRESS contains a list of these packages 
and a short description of each. [MAXC]XMESALIB>MESSAGE.TXT contains information on 
some not so formally documented packages. 


[MAXC]<SDSUPPORT> 
Contains CR*.LOG, the logs of change requests for the Mesa system (as explained in Section 


1.8). Any problems with the Mesa system should be reported to <SDSUPPORT>. Submitting 
packages to <MESALIB> is also done through <SDSUPPORT>. 


Section 3: Resources 


The following list enumerates resources that may be of interest to Mesa programmers. They can all 
be obtained through the support group. 
Documents 
Mesa Language Manual 
Complete reference on the language, syntax, and use of Mesa. 
Elements of Mesa Style 
Describes some of the novel features of Mesa using a number of examples oriented towards 
the systems programmer. It concentrates on compile-time checking, interfaces, and 
modularity. 


Mesa System Documentation 


Describes configurations of the Mesa system software and the components which comprise 
them. 


OIS Mesa Functional Specification 
Describes the implementation of the runtime support necessary to execute Mesa programs. 
It assumes a Dstar machine, rather than an Alto, and is quite detailed (not for the 
beginner), 


OIS Processor Principles of Operation 


Describes the architecture of the OIS Digital Processor. It includes a description of the 
virtual storage system, the instruction set, and the input-output facilities. 


Mesa Debugger Documentation 
Describes the current release of the Mesa debugger. 
Debugger - Extended Features 


Describes some extended features of the Mesa debugger: Ftp command and user invoked 
procedures, 


Ftp Functional Specification 


Describes the procedural interface to the Mesa Ftp (file transfer) Package. 
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Mesa Pup Package Functional Specification 


Describes the procedural interface to the Pup Package. Pups (PARC Universal Packets) 
represent the lowest level interface to the ethernet. 


Change Summary 
Compiler Update 
Binder Update 
System Update 
Microcode Update 
Debugger Update 
Handbook Update 
Pup and Ftp Update 


These memos describe the changes made to Mesa since the last release. 


Papers 

Early Experience with Mesa October, 1976 
Discusses issues involved in using Mesa for systems programming (written by the designers 
of the language). It is recommended for those interested in the philosophy behind the 
language (not for the beginner). 

Mesa: A Designer’s User Perspective Febuary 28, 1978 
Discusses data typing, constructors, and signals as conceived by the designers and how they 
worked out in practice. 

The Impact of Mesa on System Design September, 1979 
Describes the use of interfaces and configurations in the development of Pilot. It focuses on 
how the scope of interfaces was limited and modularity preserved without sacrificing strict 
type checking. 

Pilot: A Software Engineering Case Study September, 1979 


Discusses the various foo/s and techniques used in the development of Pilot. It lists 
strengths and deficiencies that were observed during the different steps of the development 
cycle. 
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Files 


<MESA>MESA. signals 
<MESA>MESA.loadmap 
<MESA>BASICMESA. signals 
<MESA>BASICMESA.loadmap 
<MESADBINDER. signals 
<MESA>COMPILER. signals 
<MESA>COMPILER.loadmap 
<MESA>XDEBUG: signals 
<MESA>XDEBUG.loadmap 


*,signals contains a list of signal names, values, and global frame addresses for various Mesa 
components. *.loadmap describes the layout of the various image files after they are built. 


<MESA>USER.CM 


A USER.CM file set up with the Mesa Bravo macros, GACHA10 for the editing font, and 
minimal printing fonts. 


<MESA>MESADISK.CM 
<MESA>MESA.CM 


The command files used for setting up a basic Mesa disk (as described in section 1.1). 
[MAXC1]<SECRETARY>MESAUSERS.dl 


Distribution list for messages to the Mesa user community. If you wish to get on this list, 
talk to your secretary or <SDSUPPORT. 


Other materials 


There have been a series of videotapes prepared which describe various features of the language 
and runtime environment. See a member of your support group for further details on the tapes 
that are currently available and where to get them. 


Appendix A: Compiler 


The Mesa compiler translates Mesa source files into corresponding object files. An object file 
contains the executable code for the module (if any), a binary configuration description (for use by 
the binder or loader), and a symbol table (for inclusion by other programs or for use by the 
debugger). By convention, an object file has a name with extension ".BCD". 


The Mesa Language Manual describes the syntax and semantics of the Mesa source language. This 
appendix describes the operation of the compiler, including the compile-time options and messages. 


Preparing Source Files 


The compiler accepts ASCII text files. In a source file, any sequence of characters that begins with 
a tZ is skipped up to (but excluding) the next carriage return (or end of file). This convention 
accomodates Bravo formatting codes. You may use such formatting in your source files as you see 
fit. Note, however, that Mesa does not interpret any information about fonts, position, etc., attached 
to source text that it displays (in, e.g., identifying the location of an error or breakpoint). 


The recommended extension for naming any Mesa source file is ".mesa".- 


Standard Bravo macros useful during the editing and compilation cycle are described later. 


Running the Compiler 
The compiler takes commands either from the command line or interactively from the keyboard. 


To enter interactive mode, type just "compiler" to the Alto Executive. The compiler will 
prompt you for commands. You can correct a command during typein by using the usual 
set of editing characters. To exit from the compiler, respond to the prompt with just a 
carriage return. 


To invoke the compiler specifying command line input, follow "compiler" with a list of 
commands, separated by spaces. In this mode, you can use the Executive’s file completion 
facilities to build the command list, and a// input is taken from the command line. 


The simplest form of command is just the name of a source file to be compiled. If you supply the 
command sourcefile with no period and no extension, the compiler assumes you mean 
sourcefile.mesa. 


During compilation, the display is turned off and a die is displayed in the cursor. The number on 
the die identifies the pass of the compiler that is running. This allows you to check the progress of 
the compilation and also provides useful feedback to the maintainers of the compiler when 
something goes drastically wrong. 


Fine point: 


Don’t confuse the compiler’s cursor with DMT's. 
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The compiler reports the result of each command with a message having one of the following forms 
(each * is replaced by an appropriate number; bracketed items appear only when relevant): 


jile.mesa -- source tokens: *, time: * 
[code bytes: *, links: *, frame size: *] 
[* warnings on file.erriog] 


Compilation was successful. The object file is fileBCD. For a DEFINITIONS module, the 
middle line is not meaningful and is omitted. Otherwise, "links" is the number of items 
imported by the module, and "frame size” is the size of the global frame (in words), 
exclusive of the links, The third line appears only if warning messages were logged. The 
compiler issues warnings for certain constructs that are technically correct but nonsensical or 
likely to be unintended. Warnings do not prevent writing a valid object file, but you 
should usually investigate them. 


file.mesa -- aborted, * errors [and * warnings] on file.errlo 
g g 


Compilation was unsuccessful. You will find the error messages (and warning messages, if 
any) in the indicated file. If the errors were detected during the early phases of 
compilation, no object file was written (and any existing object file with the same name 
remains valid). Otherwise, the object file was invalidated and will be rejected by the binder 
and loader. 


File error 
The compiler could not find the specified file. 


If you are providing commands interactively, these messages appear on the Alto screen after each 
command js completed. Otherwise, they are written into the file MESA.TYPESCRIPT. In the latter 
case, the compiler will process the entire command line; then, if any error or warning messages 
were issued, it brings this to your attention with a message of the form: 


Errors [and Warnings] logged; type any character to finish. 


The compiler will not return to the executive or run another subsystem until you acknowledge the 
message. (You can change this behavior by using switches, which are described next.) 


Compiler Switches 


Switches allow you to modify command input. A command has the general form 
file[/s] 


where {] indicates an optional part and s is a sequence of switch specifications. A switch 
specification is a letter, identifying the switch, optionally preceded by a ’-’ or ’~’ to reverse the 
sense of that switch. The valid switches are 


compile code for an Alto (default) 

bounds checking 

cross-jumping optimization 

NIL pointer checking 

pause after compiling file if there are errors 

terminate compilation and run the program contained in file 
sort global variables and entry indices (default) 


"yun DU Se oO Dp 
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u unitialized variable checking 
w log warning messages (default) 
Each switch has a default setting, The command sourcefile is equivalent to 


sourcefile/a~b~j~n~ps~uw if you use the standard defaults, i.e., the compiler generates code 
for an Alto (not a Dstar), does not cross-jump the code, does not pause after compiling fi1e, sorts 
variables, and logs warning messages. It does not do bounds, NIL pointer, or uninitialized variable 
checking, Note that the "r" switch changes the interpretation of file, which should name a 
subsystem when used with this switch. 


You can also change the default setting of any switch by using the "c" switch. The text preceding 
a "/c" is interpreted as a switch specification (designating a single switch only) and it establishes 
the default setting for that switch. Unless overridden or reset, that default applies to all subsequent 
commands. 


Here is some information about the options: 
a[1to] 
Generate code for Alto (a) or DStar (-a) hardware. 
b[ounds ] 


If bounds checking is specified, the compiler inserts code to check that values are within 
range for all assignments to subrange variables and all indexing operations. Checking is 
also inserted for all assignments of signed values to unsigned variables and vice-versa. If 
the value is out of range, the signal BoundsFault is raised (see Mesa System 
Documentation). The compiler performs some bounds checking during compilation and 
does so independently of the setting of the 'b switch. If it can deduce that no bounds 
failure is possible, the run-time check is omitted; if a bounds failure is unavoidable, it 
reports the error during compilation. Compile-time bounds checking is based upon the 
assumption that all variables are initialized before use. 


Fine Point: Bounds checking in indexing operatons is a/ways suppressed if the declared index type is 
empty, eg., [0..0). 


jLumped] 


Cross-jumping is a peephole optimization technique that potentially shortens the object 
code. The reduction in code size can range from negligible to 20% depending upon coding 
style. If cross-jumping is specified, the correspondence of source to object is no longer one- 
to-one. This affects the debugger’s ability to set breakpoints and identify code locations 
(see Mesa Debugger Documentation). 


nLilj 


If Nit checking is specified, the compiler inserts code to check for a null value prior to any 
operation that dereferences a pointer. Note that indexing operations using an array 
descriptor or a string also imply dereferencing and are checked. If the pointer value is NIL, 
the signal PointerFault from interface TrapDefs is raised. No compile-time checks for NIL 
are performed. 


Fine Point: No NIL checks are provided in the dereferencing of relative pointers. 
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Depending upon coding style, these run-time checks can increase the size of the compiled 
code substantially. 


sLort] 


Normally, the compiler sorts certain items by frequency of use before assigning addresses. 
This helps to keep the object code compact. If sorting is suppressed (~s), the assignments 
of global frame offsets and entry indices depend only upon order of declaration in the 
source text. This switch was added in anticipation of tools allowing inexpensive correction and replacement 
of modules in a configuration. These tools are not yet available. 


u[ninitialized variables] 


If check is enabled, the compiler issues warning messages for uses of apparently 
uninitialized variables (but not fields of records). The algorithm used to detect suspicious 
usage is based upon the following assumptions: 


The entire body of a procedure is executed before the bodies of any procedures 
declared within it. 


Within any procedure, the order of execution is equivalent to the order of 
appearance of source text (for the purposes of variable initialization). 


The bodies of the contained procedures are executed in order of appearance. 


The algorithm works fairly well for detecting certain common errors, but it is obviously not 
foolproof. There is no guarantee that all uses of potentially uninitialized variables are 
reported, conversely, properly initialized variables are sometimes flagged when the 
initialization depends upon the order of execution of subprocedures. (Performance with 
respect to global variables is improved by putting the initialization code for a module either 
in the main body or the lexically first procedure.) 


wlarnings ] 


Log (w) or ignore (-w) certain legal but suspicious usage that can be detected by the 
compiler. 


Examples: 


foo 


Compile foo using all the default switch settings (standard or established by preceding 
"7c" switches). 


foo/-wj 


As above, but suppress warning messages and do cross-jumping. 


The p[ause] switch requires special comment. You can use it to control progress through a 
sequence of files specified on the command line. As a global switch (set using "/c”"), it specifies 
pausing (p) or not pausing (-p) just before exiting from the compiler; the global default is to pause. 
As a local switch, it specifies pausing just after compiling the specified file if that file or any 
preceding file contained errors; moreover, any remaining commands are ignored. The local default 
is not to pause but to continue with the next input file. 
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Examples: 


compile -p/c file1 file2 file3 


Use this form if you want the compiler to press on no matter what. If it is part of a 
command file, the next (Executive) command will be executed whether or not there were 
errors. 


compile filei file2/p files 


Use this form if you want the compiler to pause before compiling file3 if either file1 
or file2 does not compile successfully. If file3 depends upon the others (by including 
them), this can save a lot of wasted time and effort. 


Context Switching and Bravo Macros 


If you are a Bravo user, you might find the following macros useful for switching between Bravo 
and the Mesa compiler. They are included in <MESA>USER.CM. 


bravo/m filename 


This invokes Bravo with two windows, gets filename,errlog in a smaller, bottom 
window, and gets filename.mesa in the top window. (Be sure not to use 
filename.mesa on the command line.) 


bravo/j filename octal number 


This invokes Bravo and gets filename.mesa. It also selects the character position 
corresponding to the octal number and normalizes the selection. This is useful when the 
source text printed with an error message does not supply enough context to locate the 
error; each error message also includes the octal number needed by this macro. 


qfuit]/m 


This Bravo command writes out the file in the selected window (say f ilename.mesa) and 
terminates Bravo. It then specifies the following sequence of (Executive) commands: 


delete filename.errlog 
compile filename 
bravo/m filename 


The command line switch "/r" (run) causes the compiler to terminate by running some other 
program instead of returning to the Alto Executive. You may specify either a ". image” or a 
". run” file; if you omit the extension, ". image” is assumed. Any switches after the "r" and any 
other text remaining in the command line after the command specifying this switch are copied to 
the file Com.cm for inspection by the new program. This facility is primarily intended for use in 
(program generated) command files. 


Examples: 


Compiler sourcefile Mesa/r sourcefile 
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Compile sourcefile: then invoke mesa. image to load and start sourcefile.bcd. 
Note that "Compiler sourcefile; Mesa sourcefile" has the same effect but is 
slower, because it returns to the Alto Executive before invoking Mesa. (There are 
overheads of several seconds associated with both restarting the Executive and reestablishing 
the Mesa environment.) 


Compiler sourcefile Ftp.run/r Iris store sourcefile.bcd 


Compile sourcefile, then store the object file on Iris. Note that you must supply the 
"\run" and “.bcd" extensions to invoke Ftp in this way. 


Fine point: 


You can run Bravo using the "/r" switch, but the current version (7.2) will not correctly find switches or 
arguments on the command line. 


Error Messages 


The compiler writes error and warning messages for sourcefile.mesa on 
sourcefile.errlog. Each pass detects certain classes of errors. Error messages are logged in 
(approximate) source order by each pass. Within a single pass, the compiler does its best to 
complete its analysis in spite of any errors. With the exception of “correctable” syntactic errors, 
detection of an error by one pass causes all following passes to be skipped. Thus you will 
sometimes get a new set of error messages after correcting all those reported by a previous run of 


the compiler. The compiler never writes a bindable or loadable object file if it detects any errors. 


The compiler also logs warning messages. These are advisory only and are intended to draw your 
attention to suspicious usage. They do not abort compilation or invalidate the object file (but they 
should be checked). : 


Here is a trivial and nonsensical program that illustrates the form of the compiler’s error messages. 


Sample: PROGRAM = 
BEGIN 
i: INTEGER, 
ji «+ j+TRUE; 
END. 


i: INTEGER, 
+ Syntax Error [46] 
Text deleted is: ; 
Text inserted is: : 


j. is undeclared, at Sample[52]: 
j «© j+TRUE; 


TRUE has incorrect type, at Sample[52}: 
i ¢ jt+TRUE; 


The first message is generated by the first pass and shows how syntactic and lexical errors are 
reported. The arrow points to the first symbol that is necessarily invalid (or one symbol before it), 
and the octal number is a character index in the source file. Of course, the compiler cannot know 
‘what you intended, and the "real" error might have occurred quite a bit earlier. The compiler tries 
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to fix these errors as best it can by local deletion and insertion of symbols. These symbols are not 
written into the source file but are reported to help you interpret subsequent messages. If the 
compiler cannot find a way to continue parsing. or if too many of these errors accumulate, it gives 


up. 


The other error messages report “semantic” errors. Errors are located by displaying a line of source 
text (the second line in each message) as well as the character index (an octal number) and the 
enclosing procedure or program name (the identifier preceding the number). The text of the error 
message is intended to be reasonably self-explanatory. Sometimes it refers to an identifier or 
expression. The compiler reconstructs these expressions from the parse tree; in later passes, the 
reconstruction often reflects rearrangement or constant folding so it may not exactly duplicate the 
source code. As subexpressions, "?" indicates an undeclared identifier and "..." indicates either 
a cutoff because of depth of nesting or an expression form the compiler cannot reconstruct from the 
parse tree, 


Compiler Failures 
The message reporting a compiler failure has the following form: 


FATAL COMPILER ERROR, at id[index]: 
(source text) 
Pass = n, signal = s, message = m 


Such a message indicates that the compiler has noticed some internal inconsistency. The compiler 
will skip the remainder of the command line if this happens. If you get such a message (or 
encounter other compiler problems), you should submit a change request (CR) as described in 
Section 1.8. Be sure to preserve the relevant files and to mention the octal codes identifying the 
pass (n), signal (s) and message (m) in your change request. 


Current Limitations 


The following limits are built into the current implementation of Mesa and are enforced by the 
compiler: 


The number of interface items declared in a single DEFINITIONS module cannot exceed 128. 


Neither the number of procedure bodies nor the number of signal codes defined in a single 
PROGRAM module can exceed 128, 


The size of the frame or record required by a procedure or program cannot exceed 4096 
words, 


The compiler allocates its internal tables dynamically and tries to adjust their relative sizes to 
accomodate the program being compiled. When it is unsuccessful, it reports failure with a message 
of the form: 


Storage Overflow in Pass n 


Usually, the best thing to do is split your program into two or more smaller modules. If the Pass is 
5, you can sometimes get your program compiled by removing code from the main body (into a 
procedure called by the main body), or reordering the procedures so that the largest ones come near 
the end. The reason that this works is that pass 5 reuses the parse tree space from earlier procedures to hold code 
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generated for later procedures. If the main body (first processed) or one of the first procedure bodies is large, there is 
not much space for the code. 


Appendix B: Binder 


The Mesa binder combines modules and previously bound configurations to produce a new 
configuration. The Afesa Language Manual documents the syntax of a configuration description 
which describes the desired configuration to the binder. The output of the binder is a binary 
configuration description (BCD) which may be loaded into a running system or processed by a later 
invocation of the binder. This section discusses the operation of the binder including the binding 
time options and switches. 


File Organization 


In order to understand the options described below, it is necessary to understand something about 
how configurations exist in files. The BcD file produced by the binder normally contains only the 
compiled description of the configuration. It does not contain any code or symbols. For each 
module instance in the configuration, the BCD specifies the location of the code and symbols by file 
name (and time stamp), starting page, and number of pages. Thus the code and symbols for a 
configuration may be scattered over a large number of files. It is possible to put the BCD, the code, 
and the symbols in the same file (this is the way BCDs are generated by the Mesa compiler). 


While debugging, the "normal" mode of operation is not to copy code or symbol segments to 
another file (the default; no switches), but to leave them in the files generated by the compiler. 
This saves disk space and requires the least binding time. 


For distribution, code and/or symbols can be copied into the output file by using the corresponding 
switch on the source file name (not on the output file name). Alternately, they can be copied into 
different code or symbols files by giving the file name and switch following the source file name. 


It is a good idea to package the symbols of a released subsystem into a separate file, so that they 
will not take up disk space when they are not in use. This also makes it easier to keep track of a 
consistent set of symbols for all of the modules. Because the binder and loader deal only with 
interfaces, symbol tables are not required for binding or loading. Of course, they are required for 
meaningful debugging. (FTP and the debugger’s ATtach Symbols command can be used to get 
symbols for individual modules during debugging.) 


There is also an option for compressing the symbol tables as they are copied. In this mode, only 
public symbols declared in the global frame (plus all procedures and signals and their parameters 
and results) are included. Private symbols and variables local to procedures are not copied. This 
option allows limited but usually adequate debugging, and will substantially reduce the size of the 
symbols file (typically by 50%). 


Fine point: 


Copying code into a file other than the BCD file is supported, but probably not useful. 
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Running the Binder 
Fine point: 


The binder is now available as BINDER.BCD as well as an image file. In the BCD form, it requires MESA.IMAGE in 
order to run. SYMBOLCOMPRESSOR.BCD must be loaded first when copying or compressing symbols. 


The binder takes commands either from the command line or interactively from the keyboard. 
Commands are of the form 


source[/s file/s file/s} 


where [] indicates optional parts. The valid switches are 


/d - enter debugging mode 

/c - copy code segments to this file 

/o - give this name to the output BCD file 
/s + copy symbol segments to this file 

/x + copy compressed symbols to this file 

/p - pause after binding if there are errors 
/r - run the specified program 

/g - (go) begin processing the preceeding files 


A switch specified with a null file name is a global switch. A switch may be preceeded by ’-’ to 
negate its effect. The only switch with either of these properties is the /p switch. The binder will 
pause after completing all commands if any errors were reported. Applying the /p switch to an 
individual source may cause a pause earlier as well. 


Normally a command to the binder is terminated with an end-of-line. In order to specify more 
than one command using command line input, the /g switch (for "go"') may be used to replace the 
end-of-line. Simply add the /g switch to the last file name of each command. (This option is not 
available when input is from the keyboard.) 


The first file name is always the source configuration description. The last occurance of a /c, /o 
or /s file will prevail, and extra filenames are ignored. Default extensions are "config" for 
source, "bed" for output, "code" for code and “symbols” for symbols. Default output is to 
source.bcd. Examples: 

foo 


Read foo.config and write the resulting BCD on foo.bcd. This is the "normal" debugging 
mode since it is the fastest and requires the least disk space. 


foo/c 
Read foo.config, write foo.bcd. Copy all code segments into foo.bcd. Leave all symbol 
segments as they were in the input files. This is a possible "distribution" mode. 
foo/cs 


Read foo.config, write foo.ocd. Copy all code and symbol segments into foo.bed. This is 
also a possible distribution mode, if debugging will be required. 
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foo/c foo/x 


Read foo.config, write foo.bcd. Copy all code segments into foo.bcd; compress all 
symbol segments into foo.symbols. By packaging all of the symbols in a single file, you 
minimize the risk of getting an incorrect version of some symbol table. 

foo.cd/c foo.sym/s foo.bound/o 
Read foo.cd, write foo.bound. Copy all code segments into foo.bound and all symbol 
segments into foo.sym. 


foo.cd/c foo.sym/sg bar/c 


Read foo.cd, write foo.bcd. Copy all code segments into foo.bed and all symbol segments 
into foo.sym, Then read bar.config and write bar.bcd. Copy all its code into bar.bcd. 


/-p foo/g bar/cg dum 
Bind foo, bar, and dum and do not pause even if there are errors. 


foo/g bar/cpg dum 
Bind foo, bar, and dum as usual; in addition, stop after bar if it contains errors. 


Because of the large number of options available, it is doubly important to maintain file consistency. 
Appropriate version checks are included in the binder, the loader, and the debugger. 


Context Switching 


The command line switch /r (run) is used to specify that the Binder should run some other 
program rather than returning to the Alto Executive. Both ". image” and ".run" files may be 
specified. If there is no explicit extension, ". image” is assumed. Any switches after the r and any 
other text remaining in the command line after the file with the /r switch will be copied to the file 
COM.CM for inspection by the new program. 


Examples: 


Binder SomeConfig/g Mesa/r SomeConfig 
will bind SomeConfig and then run Mesa.image as if you had typed Mesa 
SomeConf ig. 

Binder SomeConfig/g Mesa/rd OtherConfig/-s SomeConfig 
will bind SomeConfig and then run Mesa.image as if you had typed Mesa/d 
OtherConfig/-s SomeConf ig. 

Binder SomeConfig/cg Ftp.run/r Store SomeConfig.bed 
will bind SomeConfig copying the code and then run Ftp.run as if you had typed 
Ftp.run Store SomeConfig.bcd. 


Fine points: 


The last specification before the file with the /r switch must have the /g switch to indicate the end of the 
previous command. 
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You can run Bravo using the /r switch, but the current version (7.2) will not find switches (or arguments) on 
the command line. 


Error Messages 


The binder reports error and warning messages on the display, in the file MESA.TYPESCRIPT and the 
file SOURCE.ERRLOG. If possible, the binder will indicate the offending source line and 
configuration name with each error. Some of the common error messages are: 

foo is undeclared (in baz) 


The module baz is trying to import the interface (or program) foo, but foo is neither 
imported from a higher lever configuration nor exported by any module or configuration at 
the same level. 
foo does not name a module or configuration 
The identifier used to name a module or configuration in a configuration description must 
exactly match (including capitalization) the name used inside that module or configuration. 
item nnn in interface foo is unbindable 


(Warning) Item number nnn in the interface foo has no implementation. You can count 
(from 0) the interface items in foo or use the lister’s Interface command to get more 
information. 


foo referenced in different versions 


(Warning) Two different versions of the named file are referenced by the modules being 
bound. This will produce another error message if you attempt to match the two versions 
as import and export. 


foo cannot be imported as baz 
foo is the interface (file name and version) which is available for import (or being passed 
aS a parameter), but the importer is asking for baz. The source line shows the importer. 


foo cannot be exported as baz 


The source line shows an exporter of foo who is trying to assign the interface (implicitly or 
explicitly) to baz. This may be a version problem (if the names are the same) or an error 
in an assignment. 


foo is not imported by any modules 
foo is not exported by any modules 


A configuration must tell the truth about what it IMPORTS and EXPORTS, i.e. everything 
imported or exported by a configuration must actually be imported or exported by a 
contained module or configuration. 


The following modules are compiled for Alto (others are not) 


An attempt has been made to bind modules compiled with the -a switch and modules 
compiled without it. 
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Errors detected, BCD not written 


The binder has produced no output. 


Errors detected, BCD is invalid 
Errors were discovered after the binder had started writing the output file. The file has 
been made invalid so that neither the binder nor the loader will accept it as input. 
Type any character to exit 


The binder will normally pause before returning to the Alto Executive (or running another 
program) if there were any errors detected. To turn this global pause flag off, use the 
switch /-p with a null file name. 


Fatal Binder Error 


Fatal errors are reported in a fashion similar to the compiler; the signal and message are 
given in octal, and should be included in any change request reporting a fatal binder error. 


Current Limitations 


The DIRECTORY clause in a configuration description should be used only when the name of a 
module or configuration differs from the name of its file. Do not make DIRECTORY entries for 
interface (DEFINITIONS) ‘files. 


The output BCD file can be renamed; the code and symbols files cannot (since the BCD contains 
the names of these files in its internal tables). 


Copying code and symbols into the same file (other than the BcD file) is not implemented. 


Multiple instantiations of nested configurations are not implemented. You can get around this by 
binding the nested configuration in a separate step. 


Estimated running time: five seconds for initialization plus one-half second per included file 
(module or configuration). Add one second per module to copy code and one second per module 
to copy symbols. 
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Appendix C: System 


Mesa systems are available in both standard and basic configurations. The basic configuration’s only 
user interface is the command line. BCDs may be loaded and started by specifying them on the 
command line. The standard configuration contains the Mesa Executive which serves as the user 
interface. See the Afesa System Documentation for details. The standard configuration also allows 
command line loading. 


Command line loading 


Both the standard configuration and the basic configurations allow clients to load their BCDs by 
specifying them on the command line. The general form of the command line is: 


>[Mesa[/d]] filei[/s] file2[/s] 
The valid switches are listed below. A ’~’ preceeding the switch inverts its meaning. 


/d -- go to the debugger after loading this BCD but before starting it. This is the only 
switch applicable to the image file. 


/s -- start the BCD (default if non-null control module). 
/1 -- load the BCD with code links. The / switch is also applicable to the New command of the 
Mesa Executive. The modules will only have code links if there is room for the links in the code and the 
modules specify that they want code links. 
The default extension for file is". bcd". Version 9 or greater of the Alto Executive inserts MESA.IMAGE (if 
it’s on the disk) in front of files ending with the extension bed. There are no global switches. All switches 
apply only to the file to which they are attached. If BasicMesa runs out of things to load from the 
command line, it returns to the Alto Executive. If Mesa runs out, the Afesa Executive is given 
control. 
Examples: 
>BasicMesa DisplayPackage/1l-s SomeConfig/d 


Start Bas icMesa and load the DisplayPackage with code links but don’t start it. Then 
load SomeConfig and go to the debugger before starting it. 


>AConfig/-s StrangeConfig.foo/-s 


Start Mesa, load AConfig.bcd and StrangeConfig.foo without starting either, then 
enter the Mesa Executive. 
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Error Messages 
Errors generated during loading or interaction with the Afesa Executive are reported by displaying 
messages. BasicMesa generates signals that will be caught by the debugger. The following error 
messages are given by the Afesa Executive: 
{File: file 
When attempting to load a BCD, file cannot be found or is an invalid BCD. If file is not 
the BCD being loaded, then it is a code file for the BCD. A BCD may be invalid because it is 


was invalidated by either the compiler or binder due to errors in its construction, or because it was produced 
by an incompatible version of the system. 


!Number 
An invalid number was typed. 
!String too long 
A string was typed that was too long. 
!File name referenced in different versions 


When loading a BCD, the interface or program name was referenced in different versions. 
Loading is continued but there may be unbound external references. 


External Debugger not installed, type DEL to abort 
An attempt was made to invoke the debugger but it has not been installed. 


The signals that may be generated by BasicMesa are listed below. See BASICMESA.SIGNALS for the 
corresponding signal values. 


BadFile[name] 


When attempting to load the BCD name, either it cannot be found, it is an invalid BCD, or 
a code file in the BCD is not available. 


VersionMismatch[ name] 


When loading a BCD, the interface or program name was referenced in different versions. 


Appendix D: Debugger 


The common facilities available in the Mesa debugger include setting breakpoints, tracing program 
execution, displaying the runtime state, and interpreting Mesa statements. It will be easiest to 
understand how to access these facilities by going through a simple example using many of the 
common commands. 


Installing the debugger 


Install the debugger from the command line of the Alto Executive by typing XDebug. To load 
programs into the debugger at the same time as installing the debugger, list the names of the programs on the command 
line: use the "L” switch to load programs with code links (to save space). For example, typing XDebug Foo/L (to the 
Alto Executive) loads Foo with code links and installs the debugger. 


Files 


The debugger itself is contained in the file xDEBUG.IMAGE. There are several other files that are 
used by the debugger and should not be edited or deleted from your disk. These are the swapping 
files used by the debugger: SWATEE (to hold the user’s core image), MESADEBUGGER (to hold the 
debugger’s core image), and DEBUG.LOG (used as a record of your debugging session). 


Signals and errors 


See the Mesa Debugger Documentation for details on the common signal and error messages you 
might receive and suggestions for recovery. 


Sample program 


The configuration we are going to use as an example is taken from the Mesa Language Manual 
(Chapter 7). The following files should be retrieved from MESA>DOC: LexiconClient.mesa, 
Lexicon.mesa, LexiconDefs.mesa, LexiconClient.bcd, Lexicon.bcd, LexiconDefs.bed, 
Lex.config, Lex.bcd, and Lex.ts (a sample typescript of the debugging session that follows). 


The sample configuration Lex consists of two modules, Lexicon and LexiconClient. After the 
modules have been compiled and the configuration has been successfully bound, you are ready to 
load and debug the program. 


Entering the debugger 


Let us assume that the configuration has been loaded and started (by typing Lex to the Alto 
Executive), and you have interrupted the program and entered the debugger for the first time (by 
holding down tSwat after the program has started). You get a herald that indicates which version 
of the debugger you are using and when it was built, followed by the current date and time, a 
‘message indicating why you entered the debugger (in this case, interrupting the program), and a 
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prompt for the first command: 


Alto/Mesa Debugger 5.0F of 21-Mar-79 20:04 
27-Mar-79 9:24 
*** interrupt *** 


Setting the context 


In order to get to a context from which you can set breakpoints in one of the modules in Lex, let's 
first check to see which configurations have been loaded by saying: 


>List Configurations [confirm] 
which responds with: 


Lex 
Mesa 
Nucleus. 


If we check the context at this point, you can see that the current module is NubControl in the 
Mesa configuration, 


>CUrrent context -- 
Module: NubControl, G: 1722248, L: 172004B, PSB: 2770B 
Configuration: Mesa. 


We need to set the current configuration to be Lex, 
DSEt Root configuration: Lex 
and find out which modules are in this configuration, 


>Display Configuration Lex 
Lexicon, G: 1504048 
LexiconClient, G: 150420B. 


Now we can set the context to be Lexicon, so that we can set some breakpoints, 


>SEt Module context: Lexicon. 


Using windows 


The debugger allows you to position and change the size of the windows as well as to set 
breakpoints and to select text to be used as type-in. The left margin of a window is used for 
scrolling; use the red mouse button to scroll up, the yellow button to thumb, and the blue button to 
scroll down. The rest of the window is a text area; you can select between characters by clicking 
the red mouse button (and extend by characters by holding down red), select a word with the 
yellow button (and extend by words by holding down yellow), and display the menu with the blue 
button. The current selection is outlined by a gray box. Type-in always goes to the window 
containing the cursor (regardless of which window is on top); if this window does not accept type- 
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in, the display blinks. See the Mesa Debugger Documentation for complete details about the user 
interface of the debugger. 


Setting breakpoints by selections 


Let's load the source text for Lexicon into a window so we can set breakpoints by pointing at the 
text. This may be done in one of two ways: either display the stack and ask to see the source (this 
loads and positions the source file for the current module into the source window of the debugger), 


>Display Stack 

Lexicon G: 150404B >s 
Source: <>--Lexicon.mesa 
>q 


or load the file into a source window by 1) selecting the file name Lexicon (the extension defaults to 
mesa), 2) moving into a source window (you may have to create a new source window first), and 3) 
choosing the Load command from the menu. Additional source windows can be created, 
destroyed, and moved around as needed, using the appropriate menu commands. 


Now move into the window containing the source file, and put this window on top. This can be 
done by either clicking the red mouse button in the left or right sections of the window header, or 
by selecting the window menu command Top. 


Suppose we want to set a breakpoint on the exit of the procedure NewNode. Scroll the window 
until this procedure is visible, then select the word RETURN inside this procedure (by using the 
yellow button for word select). Hold down the menu button (blue button) and choose the 
SetBreak command. This sets a breakpoint on the exit of the procedure (similarly, selecting the 
word PROCEDURE sets a breakpoint on the entry to the procedure). 


Suppose you want to set a breakpoint in the end of one of the conditional IF-THEN-ELSE statements 
in the procedure InsertString. This can be done by selecting any place in the statement ELSE 
n.llink «© NewNode[];. Confirmation of where the breakpoint has been set is given by the 
moving the selection to ELSE <>n.Ilink « NewNodef[]; (Note that in all cases, the closest enclosing 
statement is the place at which the breakpoint is actually set). 


Setting breakpoints by type-in 


You may also set breakpoints in the program by means of typing in the command. This gives you 
the added capability of specifying a condition that must be satisfied in order for the breakpoint to 
be taken. If, for instance, you want to set a breakpoint on the entry to the procedure FindString, 
and enter the debugger only if the root is not NIL, move the cursor back into the DEBUG.LOG 
window and say: 


Break Entry procedure: FindString, Condition: root # NIL. 
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Inserting comments 


Saving some comments along with the commands is a good idea, so that it is easier to remember 
what happened when looking back at the typescript file. For instance you might now say, 


>--This breakpoint was set to skip checking for a lexicon if we 
>--know the tree is empty. 

Proceeding 

It is now time to proceed and run the program. This is done by executing the following command: 
>Proceed [confirm]. 


If we try to add the lexeme "xxxxx" to the tree, we will then reach our breakpoints. 


Examine and change the state 
You next enter the debugger at the first breakpoint with the herald: 
>Break at exit from NewNode, L: 1650648 (in Lexicon, G:150404B) 
to indicate where you are. At this point you might display the stack and look at the variables, 
>Display Stack 
NewNode, L: 165064B (in Lexicon, G:150404B) >v 
n=163732Bt >q 
or look at the several levels of the stack, 
>Display Stack 
NewNode, L: 165064B (in Lexicon, G:150404B) On 
InsertString, L: 165074B (in Lexicon, G:150404B) Dn 
AddString, L: 166104B (in Lexicon, G:150404B)  >n 


LexiconClient, L: 171674B (in LexiconClient, G:150420B) >n 
No symbols for NubControl, G: 172224B, L:172074B, PC: 307B, E 


>q 
or ask to see what the node n (in NewNode) looks like (invoke the interpreter by typing sp), 


> nt 
Node[llink:NIL, rlink:NIL, string: (5,5)"xxxxx"], 


Let’s say we wanted to set both the left link and right link of n to point to n itself and then check 
the value of n. This may be done by saying, 


> n.Jtink © n 3; nv.rlink © n 3; n 3 nt 


which responds with, 
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163732Bt 
Node[11ink:163732Bt, rlink:163732Bt, string:(5,5)"xxxxx"}. 


If at this point we want to see the value of the variable ch in the module LexiconClient (a 
variable in the current configuration but not in the current module), this may be done by saying, 


>Find variable: ch 
which responds with the first character of the last command that was typed, 


"a (in LexiconClient). 


More breakpoint commands 
The following command lists all of the breakpoints that have been set: 
>List Breaks [confirm] 
Exit from NewNode (in Lexicon, G:150404B) 
Entry to FindString (in Lexicon, G:150404B) 
Condition: root # NIL 
In InsertString (in Lexicon, G:150404B) 
Source: ELSE <>n.11link ¢ NewNodef ]; 
If you decide that you are no longer interested in any of these breakpoints you can 
>Clear Al? Breaks [confirm] 


which removes all breakpoints and restores the instructions. 


Look at the user world 

If you are interested in seeing the state of the user display, you can look at the user world by saying 
>Userscreen [confirm]. 

When you want to return to the debugger, hit either the SwaT key or FRS5; this brings you back 

into the debugger, ready to execute more commands. 

Setting tracepoints 


Suppose next you want to set a trace on the entry to the procedure LexicalCompare so that you 
can simply see the two strings being compared and go on. You may do so by Saying, 


>Trace Entry procedure: LexicalCompare. 
Now we should proceed 


>Proceed [confirm] 
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and try to add a new lexeme. say “yyy”. 


When the tracepoint is reached, you get the herald indicating why you entered the debugger, where 
you are, and a dump of the input parameters of the procedure: 


Trace at entry to LexicalCompare, L: 165334B (in Lexicon, G:150404B) 
si=(3,80)"yyy" 
$2=(5,5)"xXxxxx" > 
at which point you may continue executing your program (respond with Q) 
>q 
or enter the debugger command processor (respond with B) 


>b 
>. 


This represents a brief introduction to the use of most of the debugger’s commands that you will 
commonly need. See the Afesa Debugger Documentation for further details; the best teachers are 
experienced Mesa programmers and lots of practice!!! 
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Appendix E: Utilities 


Described below are several utility packages that have proved useful in building Mesa systems. The 
Lister produces symbolic listings of various Mesa file formats. The JncludeChecker checks for 
object file consistency. The Statistics package generates source and object statistics. Version lists 
creation dates for source and object files. The SignalLister produces a mapping of signals and 
signal values. 


Lister 


The Lister produces listings of code, symbols, beds, etc. from object and source files. To use it, 
retrieve <MESA>LISTER.IMAGE Or LISTER.BCD (this requires MESA.IMAGE). The Lister operates in either 
command line or keyboard mode. Commands look like procedure calls with constant (string, 
numeric, character, boolean) arguments. Note that many of the commands are useful only for 
internal (compiler) debugging. Arguments are type checked by the command interpreter. In 
command line mode, type to the Alto Executive: 


>Lister commandi[argi, arg2, ...] command2[arg1, ...] 
You actually type the square brackets, as in a Mesa procedure call. 


In keyboard mode you just type the command with arguments. Typing the Esc key will extend the 
command name if a unique command exists. The Lister will prompt for arguments if the command 
name is terminated with cr. Typing ? in keyboard mode will produce a list of available commands 
and their arguments. The current commands are: 

Code[ "Filename" ] 


Given a bcd file produced by the compiler, this command produces a listing of the object 
code (on Filename.ctl). If the source file is available on your disk, the source for each 
statement is listed just before the object code. 


Warning: This command produces a large amount of output. 

OctalCode[ "Filename" ] 
Same as the Code command, except that opcodes are given in octal as well as by name. 
Warning: This command produces a large amount of output. 

OpcodeList[ "Filename" ] 


Generates a one page (Gacha8) listing of the Mesa opcodes (on Filename.1ist). 


Bed[ "Filename" } 


Given output of either the compiler or binder, this command produces a listing of the 
internal tables of the binary configuration description (on Filename.b1). 


BedLinks["Filename" ] 


Same as the Bcd command, except that the control links of imported and exported items 
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are included. 


BcdSegment[ "Filename" ,Base,Pages,Links ] 


The most general form of the Bcd command allowing you to specify the location of the 
BCD by filename, starting page number. number of pages, and whether you want the links 
(specify TRUE or FALSE). 

Interface["Filename" ] 


Given the BCD file for an interface (DEFINITIONS file), this command produces a list of the 
interface items and numbers (on Filename.il). These numbers are the ones reported by the 
Binder for unbindable items. 

Symbols["Filename" ] 
Given a compiler output ecb, this command lists the internal symbol table (on 
Filename.s1). 

SymbolSegment[ "Filename" ,Base, Pages ] 


A more general form of the Symbols command allowing complete specification of the 
location of the symbols (eg. in a .symbols file). 


Bodies["Filename” ] 


Given a compiler output BCD, this command lists the bodies from the internal symbol table 
(on Filename.s1). 


BodySegment[ "Filename", Base, Pages] 


A more general form of the Bodies command allowing complete specification of the 
location of the symbols (eg. in a .symbols file), 


FGTable[ "Filename" ] 


Given a compiler output BCD, this command lists the fine grain table from the internal 
symbol table (on Filename.f1). 


Using["Filename" ] 


Given a compiler output BCD, this command generates a directory statement with its 
included identifier lists (on Filename.ul). Since there is not enough information in the BCD to 
tell which symbols were implicitly included, the USING clauses will contain a superset of those items actually 
needed. 


UsingList[ "Filename" ] 
Given a file containing a list of compiler output BCDs (in Filename), this command 
creates the ".ul" files, 


Xref["Filename", Include Private Symbols?, Procedures Only?] 


Given a compiler output BCD or a file containing a list of BCDs, this command produces an 
alphabetical symbol listing (on Filename.xref). If Include Private Symbols? is 
FALSE, only public symbols are listed. If Procedures Only? is TRUE, only procedures 
and signals (but no types) are included. Multiple ouptut files are created if the listing exceeds 50K 
characters (since Bravo formatting is included). 
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Run[ "Filename" ] 


Invokes another image file (if extension is image) or a BCPL program (if extension is .run). 
If no extension is specified, .image is assumed. 


Image[ "Filename" } 


Makes an image file. If no extension is specified, .image is assumed. 


Load["Filename” ] 


NEWs and STARTs the module Filename. An escape hatch allowing other programs to run in the 
Lister environment. 


Debug[ ] 
Invokes the Debugger. 
Quitf] 


Returns to the Alto Executive. 


Include Checker 


The IncludeChecker is a program that checks the include relationships in bcds for consistency. It 
accepts switches on the command line to control the three part output (compilation order, includes 
relation, and included by relation). Any inconsistencies are flagged with an asterisk. In addition, an 
optional consistent compilation command file is written on Line.cm. To use it retrieve 
<MESAD>UTILITIES>INCLUDECHECKER.BCD. The IncludeChecker gets all of its parameters from the 
command line and is started by typing to the: Alto Executive: 


>IncludeChecker [outputfile][/switches] [filenamel filename2 .. .] 
where 


outputfile is the name of the file written. If none is specified, the file "Includes" is 
assumed. If no extension or switches are given, ".1ist" is assumed. 


/C consistent compilation command will be written in Line.cm. It will also list BCDs 
and sources not on the disk needed to do the compilation. 


fi do both the includes and included by relationships (default); -i does neither. 
/m use multiple output _ files. The compilation order is written on 


“source” ..outputfile. The extensions ". includes" and ".includedBy" 
are used instead of ".1ist" for the include relations. 


/0 compilation order for [filenamei filename2 . . .] (default). 
/s same aS /c-i-0. 
filename1 fitename2 . . . is the list of file names specifying the BCDs to be checked. 


If no files are specified, all BCDs on the disk are examined. 
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For example, the following command line will produce the output shown below on file Foo. list. 
>IncludeChecker Foo Allocator AitoDefs FspDefs InlineDefs MopCodes 
SystemDefs Table 
// Complete Compilation Order: 
Mopcodes InlineDefs FspDefs Systemdefs Table Allocator AltoDefs 
Allocator (15-Feb-79 9:28:12 #5 #20) includes 

InlineDefs (13-Feb-79 16:30:33 #5 #20) 

Systemdefs (13-Feb-79 16:40:21 #5 #20) 

Table (13-Feb-79 16:30:47 #5 #20) 
AltoDefs (13-Feb-79 16:28:26 #5 #20) includes nothing 
FspDefs (13-Feb-79 16:36:59 #5 #20) includes nothing 


InlineDefs (13-Feb-79 16:30:33 #5 #20) includes 
Mopcodes (13-Feb-79 16:30:17 #5 #20) 


Mopcodes (13-Feb-79 16:30:17 #5 #20) includes nothing 


Systemdefs (13-Feb-79 16:40:21 #5 #20) includes 
FspDefs (13-Feb-79 16:36:59 #5 #20) 


Table (13-Feb-79 16:30:47 #5 #20) includes nothing 
Allocator is included by nothing 
AltoDefs is included by nothing 


FspDefs is included by 
Systemdefs 


InlineDefs is included by 
Allocator 


Mopcodes is included by 
InlineDefs 


Systemdefs is included by 
Allocator 


Table is included by 
Allocator 
Statistics Package 
This package gathers statistics about Mesa source and object files and writes them on 


MESA.TYPESCRIPT. It may be invoked either interactively or from the command line. To invoke it 
from the command line, type the following to the Alto Executive: 
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Statistics filename[/switches ] 


Output is to the display and to MESA.TYPESCRIPT. If no filenames are specified on the command 
line, Statistics enters the interactive mode. Type ? to get full documentation. The following 
switches are used: 

/b -- bed statistics (default). 

/c -- command: use filename as switch. 

/d -- invoke debugger. 

/h -- print heading (default). 

/m -- source statistics (default). 

/s -- print subtotal. 

/t -- print total. 


/x -- “Management” statistics (ie. chars, lines, code bytes, and frame sizes). 
The following command line will generate the output shown below: 


>Statistics AlFont DisplayControl StreamIO SystemDisplay t/c 


Alto/Mesa Statistics Package 5.0D 


Statistics as of 27-Mar-79 10:37:48 


chars lines code frame ngfi nilinks code symbol 

bytes size pages pages 

AlFont 6264 213 556 4 1 6 2 11 
DisplayControl 6122 199 708 52 1 27 2 16 
Streaml0 5988 255 880 7 1 5 2 10 
SystemDisplay 15842 542 1800 65 2 8 4 22 
TOTAL: 34216 1209 3944 128 5 46 10 58 


Version 


Version is a program which displays time stamp information for files with any of the following 
extensions: mesa, config, bcd, image, symbols, and code. For source files (mesa and 
config extensions) it reads the first page of the file and trys to find a valid date. For binary files 
(bcd, image, symbols, and code) it knows where to find the time stamp that Mesa uses for 
version checking. When given a file name root, Version searches the disk for files with that root 
and the above extensions, displaying the time stamp for each file found. 


Version may be run either from the command line or interactively. To run Version from the 
command line type the following to the Alto Executive: 


>Version [filenamel filename2 . . .] 


To run Version interactively, omit the list of filenames in the above line. Version will then prompt 
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for input. 
Sample output is shown below. 


Alto/Mesa 5.0F of 20-Mar-79 18:00 
27-Mar-79 10:41 
>Version -- 150440B 


Mesa 
config: 28-Feb-79 9:34:00 
symbols: 20-Mar-79 17:58:50 5S#156B# 
image: 20-Mar-79 18:00:55 5#156B# 


AltoDefs 
mesa: 25-Jan-78 17:49:00 
bcd: 13-Feb-79 16:28:26 5#20B# 


SignalLister 
SignalLister is a program which will produce a signal listing for an image file, (¢.g., MESA.SIGNALS). 
It can also list the starting PC and length of procedures within an image file, (e.g., MESA.PROCS). 
This information is particularly useful to determine what procedures are on the stack when there are 
no symbols on the disk or as an aid to repackaging code. To produce a signal listing for 
FOO.IMAGE, type to the Alto Executive: 
>SignalLister Foo[/switches ] 
where 
/p lists byte PC, length, and names of the procedures in Foo on FOO.PROCS. 
/s list signals of Foo (default) on FOO.SIGNALS. 
If the symbols for a module are not available, no signals for that module are listed. For example, if 
FOO.IMAGE was made by loading FOO.BCD on top of MESA.IMAGE, a complete signal listing for 


FOO.IMAGE will require that MESA.SYMBOLS and all the symbols for FoO.BCD be on the disk. If 
MESA.SYMBOLS is not present, only those modules from FOO.BCD will have their signals listed. 
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Appendix F: RunMesa 


RunMesa.run is the program which converts your Alto into a Mesa machine, by loading the 
Alto/Mesa microcode and then loading your image file into memory. The only thing you need to 
know is that you must have RunMesa.run on your disk in order to run Mesa programs. The Alto 
Executive will automatically invoke RunMesa when you ask it to run an image file. The sections 
below describe various other features of RunMesa. All are fine points. 


Versions 


When RunMesa starts it prints out several version numbers. If you are not good at speed reading, see /V below to 
make the version stay on the screen longer. The version line looks like: 


RunMesa a.b, microcode c[d]; ROM1 microcode eff] 


a.b is the major and minor version of the RunMesa Bep] and Asm code. c is the version of the Alto/Mesa microcode 
included in RunMesa. [d}. when present, is the version of XMesa overflow microcode included in RunMesa. When 
ROM] is present, e[f] are the Alto/Mesa and XMesa versions of the microcode in ROM1. An example of a version line 
for Mesa 5.0 RunMesa (running on an Alto with Mesa 4.1 ROMs) is: 


RunMesa 32.7, microcode 39[3}: ROM1 microcode 34 


Switches 


Instead of letting the Executive automatically invoke RunMesa you may run it directly by saying RunMesa/globalSwitches 
Arguments/localSwitches. The following global switches are recognized: 


/G End of commands; ignore rest of command line. 

/M Load the Mesa microcode and exit. 

/Q Same as /G. 

/R Use the RAM instead of ROMI1. (No effect if ROM] does not exist.) Normally RunMesa expects 


the Mesa microcode to be in ROM1 if it exists. If for some reason you do not want to use ROM1, 
you may provide your own microcode for the RAM and RunMesa will load it for you. /R also 
changes the default starting address for the microcode to 20 (see local switch /S). 


4S Invoke Swat after the image file is loaded into memory but before it is started. 


IN Print out the version of the image file about to be run (and the version of its creator). Type any 
character to proceed with execution or F to abort. You may supply any other file with compatible 
header format (.bcd, .code, and symbols files are compatible) and RunMesa will give you the 
creation and creator of the file, but will refuse to run it. 


The following local switches are recognized: 


/B The argument is the name of a boot file to be run. After the microcode is loaded, the named file is 
booted using the Alto OS BootFrom operation. Default name: Mesa; default extension: sv. 


/C Same as /I] (below) except the remainder of the command line is ignored. 
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/M 


1S 


RunMesa 


The argument is the name of the image file to be executed. A file name with no switches has the 
same effect. Default name: Mesa; default extension: image. 


The argument is the name of a microcode file to be loaded into the RAM in packed ram format (cf. 
PackMu). This could be a different version of the Alto/Mesa microcode, or if you have Alto/Mesa 
microcode in ROM, you can have RunMesa load any other microcode for you. 


The argument is the octal address in the RAM at which the Mesa microcode expects to receive 
control. Default: 420. 


RunMesa rewrites Com.cm (if necessary) to remove itself and all other arguments and place the image file name first. 
An image file cannot tell whether it was invoked from the Executive or as an argument to RunMesa. 


Front 


Front.run is the part of RunMesa.run that loads the microcode and Mesa code. Front can be added to the front of an 
image file to turn it into a self-contained run file. None of the options listed above are available with Front. Here are 
the steps to make a self-contained file: 


1. 


Get Front.run from the same place you get RunMesa.run. 


2. Run it by saying "Front” to the Executive. Make sure that the microcode version it prints out is the same 
as the one you usually get from RunMesa. This operation also insures that the image file will start at a page 


boundary 


3. 


in the file. 


Concatenate Frontrun and your image file by saying 


Copy Foo.run ¢ Front.run Foo.image 


to the Executive. 


Make sure you have enough disk space when you start. Front adds about 45 pages to an image file. 


